src/features/study/participation/ui/reservation-list.tsx-117-127 (1)

117-127: ⚠️ Potential issue | 🟡 Minor

총 인원 표시가 undefined로 노출될 수 있습니다.

데이터 로딩 전에는 data?.total이 undefined라 사용자에게 "총 undefined명"이 보일 수 있어요. 동시에 Tailwind 클래스 순서도 가이드에 맞게 정렬해주세요.

🛠️ 제안 수정

-          <div className="text-text-subtlest font-designer-24b">
-            총 {data?.total}명
+          <div className="font-designer-24b text-text-subtlest">
+            총 {data?.total ?? 0}명
           </div>
...
-        titleClassName="text-text-strong font-designer-28b"
+        titleClassName="font-designer-28b text-text-strong"

As per coding guidelines: **/*.{tsx,ts,jsx,js}: Organize Tailwind CSS classes using prettier-plugin-tailwindcss for automatic class ordering and sort them alphabetically within groups`.

src/components/ui/filters/view-mode-toggle.tsx-1-2 (1)

1-2: ⚠️ Potential issue | 🟡 Minor

'use client' 지시어 누락

이 컴포넌트는 onClick 이벤트 핸들러를 사용하므로 클라이언트 컴포넌트입니다. Next.js App Router에서 클라이언트 상호작용을 위해 'use client' 지시어를 추가해야 합니다.

🔧 수정 제안

+'use client';
+
 import React from 'react';
 import { cn } from '@/components/ui/(shadcn)/lib/utils';

src/components/ui/filters/sort-dropdown.tsx-1-2 (1)

1-2: ⚠️ Potential issue | 🟡 Minor

'use client' 지시어 누락

이 컴포넌트는 onClick 이벤트 핸들러를 사용하므로 클라이언트 컴포넌트입니다.

🔧 수정 제안

+'use client';
+
 import React from 'react';
 import { cn } from '@/components/ui/(shadcn)/lib/utils';

src/components/voting/voting-modal-header.tsx-24-29 (1)

24-29: ⚠️ Potential issue | 🟡 Minor

아이콘 닫기 버튼에 접근성 라벨 추가

현재 아이콘만 있어 스크린리더가 버튼 의미를 알기 어렵습니다. aria-label(또는 숨김 텍스트)을 추가해주세요.

✅ 수정 예시

         <button
           onClick={onClose}
           disabled={disabled}
+          aria-label="닫기"
           className="rounded-100 text-text-subtle hover:bg-fill-neutral-subtle-default hover:text-text-strong p-100 transition-colors disabled:cursor-not-allowed"
         >

src/features/study/one-to-one/archive/model/use-bookmark-mutation.ts-30-35 (1)

30-35: ⚠️ Potential issue | 🟡 Minor

북마크 수 음수 방지 필요

Line 33-35에서 기존 bookmarks가 0/undefined인데 isBookmarked=true인 경우 -1로 내려갈 수 있습니다. 최소 0으로 클램프해주세요.

✅ 수정 제안

-                    bookmarks: item.isBookmarked
-                      ? (item.bookmarks ?? 0) - 1
-                      : (item.bookmarks ?? 0) + 1,
+                    bookmarks: item.isBookmarked
+                      ? Math.max(0, (item.bookmarks ?? 0) - 1)
+                      : (item.bookmarks ?? 0) + 1,

src/features/study/one-to-one/archive/api/update-archive.ts-16-25 (1)

16-25: ⚠️ Potential issue | 🟡 Minor

응답 payload 누락 시 undefined 반환 위험이 있습니다.

Line 20-25에서 data.data와 data.content가 모두 없으면 undefined가 반환됩니다. 호출부 런타임 오류 방지를 위해 payload 체크 후 에러 처리(또는 기본값)를 추가하고 반환 타입을 명시해주세요.

🛡️ 제안 수정안

-export const updateArchive = async (
+export const updateArchive = async (
   id: number,
   request: UpdateArchiveRequest,
-) => {
+): Promise<UpdateArchiveResponse> => {
   const { data } = await axiosInstance.patch<{
     data?: UpdateArchiveResponse;
     content?: UpdateArchiveResponse;
   }>(`/archive/${id}`, request);
 
-  return data.data ?? data.content;
+  const payload = data.data ?? data.content;
+  if (!payload) {
+    throw new Error('Update archive response is empty');
+  }
+  return payload;
 };

docs/balance-game-tag-filter-request.md-11-13 (1)

11-13: ⚠️ Potential issue | 🟡 Minor

tag/tags 표기 불일치 수정 필요

변경 요약의 tag 표기가 API 섹션의 tags와 충돌합니다. 문서 전반을 실제 쿼리명으로 통일해 주세요.

✏️ 수정 제안

- - 프론트는 태그 입력 후 Enter 또는 "적용" 버튼 클릭 시 `tag` 쿼리로 요청
+ - 프론트는 태그 입력 후 Enter 또는 "적용" 버튼 클릭 시 `tags` 쿼리로 요청
- - 태그 필터 해제 시 `tag` 파라미터 제거
+ - 태그 필터 해제 시 `tags` 파라미터 제거

docs/balance-game-tag-filter-request.md-44-46 (1)

44-46: ⚠️ Potential issue | 🟡 Minor

코드 펜스 언어 지정 필요 (MD040)

정적 분석 경고가 있어 예시 요청의 코드 블록에 언어를 지정해 주세요.

✏️ 수정 제안

-```
+```http
 GET /api/v1/balance-game?page=1&size=10&sort=latest&status=active&tags=frontend,react
-```
+```

src/features/study/one-to-one/balance-game/ui/tag-autocomplete.tsx-236-248 (1)

236-248: ⚠️ Potential issue | 🟡 Minor

선택된 태그 버튼에 border 클래스 누락

Line 242의 선택된 태그 버튼에 border 클래스가 없어서 border-border-subtle 스타일이 적용되지 않습니다. balance-game-filters-bar.tsx의 동일한 패턴과 일관성을 위해 추가가 필요합니다.

🔧 수정 제안

           <button
             key={tag}
             onClick={() => onRemoveTag(tag)}
-            className="rounded-100 border-border-subtle font-designer-13b text-text-subtle hover:border-border-brand hover:text-text-brand max-w-full truncate px-200 py-150 transition-colors"
+            className="rounded-100 border border-border-subtle font-designer-13b text-text-subtle hover:border-border-brand hover:text-text-brand max-w-full truncate px-200 py-150 transition-colors"
           >

src/features/study/one-to-one/balance-game/ui/balance-game-filters-bar.tsx-347-358 (1)

347-358: ⚠️ Potential issue | 🟡 Minor

선택된 태그 버튼에 border 스타일 누락

선택된 태그를 표시하는 버튼(Line 354)에 border 클래스가 없어서 border-border-subtle 스타일이 적용되지 않습니다.

🔧 수정 제안

             <button
               key={tag}
               type="button"
               onClick={() => onRemoveTag(tag)}
-              className="rounded-100 border-border-subtle font-designer-13b text-text-subtle hover:border-border-brand hover:text-text-brand px-200 py-150 transition-colors"
+              className="rounded-100 border border-border-subtle font-designer-13b text-text-subtle hover:border-border-brand hover:text-text-brand px-200 py-150 transition-colors"
             >

src/features/study/one-to-one/archive/ui/archive-grid.tsx-75-81 (1)

75-81: ⚠️ Potential issue | 🟡 Minor

handleCancel에서 description의 null 처리 누락

archive-list.tsx와 동일한 이슈입니다. item.description이 null일 수 있지만 state는 string 타입입니다.

🐛 수정 제안

  const handleCancel = (e: React.MouseEvent) => {
    e.stopPropagation();
    setIsEditing(false);
    setTitle(item.title);
-   setDescription(item.description);
+   setDescription(item.description ?? '');
    setNextPrivate(!!item.isPrivate);
  };

src/features/study/one-to-one/balance-game/api/balance-game-api.ts-24-25 (1)

24-25: ⚠️ Potential issue | 🟡 Minor

댓글 목록 조회 엔드포인트에 페이지네이션 설명 추가 필요

getBalanceGameComments 함수(101줄)에서 page = 0을 사용하는 이유에 대한 설명이 없습니다. 게임 목록 조회(getBalanceGameList)는 백엔드가 1부터 시작하는 페이지를 사용하고, 댓글 목록 조회는 0부터 시작하는 페이지를 사용하는 것으로 보아 두 엔드포인트가 다른 페이지네이션 방식을 지원하는 것으로 확인됩니다. 코드 의도를 명확히 하기 위해 101줄에 페이지 인덱싱 차이에 대한 주석을 추가해주세요.

src/features/study/interview/ui/study-ready-modal.tsx-199-205 (1)

199-205: ⚠️ Potential issue | 🟡 Minor

'참고 자료' 필드의 required 여부를 문구와 일치시켜 주세요.
helper는 선택 입력을 암시하지만 required가 설정돼 있어 혼란이 생길 수 있습니다. 선택 입력이면 required를 제거하고, 필수라면 helper 문구를 수정해 주세요.

🧩 선택 입력 기준 수정 예시

           <FormField<StudyReadyFormValues, 'link'>
             name="link"
             label="참고 자료"
             helper="함께 참고할 문서나 링크가 있다면 입력해 주세요"
-            required
             direction="vertical"
           >

src/components/ui/modal-shell.tsx-32-34 (1)

32-34: ⚠️ Potential issue | 🟡 Minor

닫기 아이콘에 접근성 레이블을 추가해 주세요.
아이콘만 있는 버튼은 스크린리더에서 이름이 비어 있을 수 있습니다. aria-label 또는 sr-only 텍스트를 추가해 주세요.

♿️ 접근성 레이블 추가

-            <Modal.Close>
+            <Modal.Close aria-label="닫기">
               <XIcon />
             </Modal.Close>

src/widgets/home/study-list-table.tsx (1)

69-98: 사용자 정보 표시 JSX가 mapDailyStudyToDisplayData 함수와 중복됩니다.

지원자/면접관 표시 JSX 구조(lines 73-78, 79-84)가 기존 mapDailyStudyToDisplayData 함수(lines 28-35, 36-43)와 동일합니다. 현재 튜토리얼용 정적 데이터이므로 큰 문제는 아니지만, 향후 유지보수를 위해 헬퍼 함수 추출을 고려해볼 수 있습니다.

♻️ 사용자 정보 표시 헬퍼 함수 추출 제안

+function renderUserInfo(image: string, name: string) {
+  return (
+    <div className="flex items-center gap-150 px-100 py-50">
+      <UserAvatar image={image} />
+      <span className="font-designer-14m whitespace-nowrap">{name}</span>
+    </div>
+  );
+}
+
 function mapDailyStudyToDisplayData(
   row: DailyStudy,
   index: number,
 ): Record<Header, React.ReactNode> {
   return {
     조: index + 1,
-    지원자: (
-      <div className="flex items-center gap-150 px-100 py-50">
-        <UserAvatar image={row.intervieweeImage} />
-        <span className="font-designer-14m whitespace-nowrap">
-          {row.interviewee}
-        </span>
-      </div>
-    ),
+    지원자: renderUserInfo(row.intervieweeImage, row.interviewee),
     // ... 면접관도 동일하게 적용
   };
 }

src/components/ui/input/base.tsx (1)

103-110: 비제어 모드에서 문자 수 표시 확인 필요

hideMeta가 false일 때 current.length를 표시하는데, 비제어 모드에서는 current가 빈 문자열이므로 실제 입력 값과 다른 "0/{maxLength}"가 표시될 수 있습니다.

💡 비제어 모드에서 ref를 통한 값 접근 고려

비제어 모드에서도 정확한 문자 수를 표시하려면 ref를 통해 실제 입력 값을 읽어야 합니다. 현재 hideMeta의 기본값이 true이므로 대부분의 경우 문제가 되지 않지만, 비제어 모드에서 meta를 표시해야 하는 경우 주의가 필요합니다.

src/components/discussion/comment-list.tsx (1)

93-97: as any 타입 캐스팅 대신 타입 가드 사용 권장

프로필 이미지 추출 로직이 두 가지 형식(문자열 URL, resizedImages 객체)을 지원하도록 개선되었으나, as any 사용은 타입 안전성을 저하시킵니다.

♻️ 타입 안전한 헬퍼 함수 제안

+// 파일 상단 또는 별도 유틸리티로 분리
+function getAuthorImage(author: DiscussionComment['author'] | VotingComment['author'] | BalanceGameComment['author']): string | undefined {
+  if ('avatar' in author && author.avatar) {
+    return author.avatar;
+  }
+  if ('profileImage' in author) {
+    const img = author.profileImage;
+    if (typeof img === 'string') return img;
+    if (img && typeof img === 'object' && 'resizedImages' in img) {
+      return img.resizedImages?.[0]?.resizedImageUrl;
+    }
+  }
+  return undefined;
+}

 // Author image handling
-const authorImage =
-  'avatar' in comment.author
-    ? comment.author.avatar
-    : 'profileImage' in comment.author
-      ? typeof (comment.author as any).profileImage === 'string'
-        ? (comment.author as any).profileImage
-        : (comment.author as any).profileImage?.resizedImages?.[0]
-            ?.resizedImageUrl
-      : undefined;
+const authorImage = getAuthorImage(comment.author);

src/components/voting/voting-edit-modal.tsx (1)

30-30: 상수를 컴포넌트 외부로 추출 권장

TAG_MAX_LEN이 컴포넌트 내부에 정의되어 있어 렌더링마다 재생성됩니다. 또한 AI 요약에 따르면 다른 balance-game 모듈에도 BALANCE_GAME_TAG_MAX_LEN = 40 상수가 있습니다.

♻️ 공유 상수 사용 제안

+'use client';

+import { BALANCE_GAME_TAG_MAX_LEN } from '@/constants/balance-game'; // 또는 해당 상수 위치
 import { zodResolver } from '@hookform/resolvers/zod';
 // ... other imports

 export default function VotingEditModal({
   // ...
 }: VotingEditModalProps) {
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [tagInput, setTagInput] = useState('');
-  const TAG_MAX_LEN = 40;

또는 해당 상수 파일이 없다면 컴포넌트 외부로만 이동:

+'use client';
+
+const TAG_MAX_LEN = 40;

 import { zodResolver } from '@hookform/resolvers/zod';

src/features/study/one-to-one/history/ui/study-history-pagination.tsx (1)

24-26: 접근성 개선을 위한 선택적 제안

유니코드 화살표 ←, →는 시각적으로는 잘 작동하지만, 스크린 리더 사용자를 위해 aria-label을 추가하거나 Lucide 아이콘(ChevronLeft, ChevronRight)을 사용하는 것을 고려해 볼 수 있습니다.

♿ 접근성 개선 제안

       <PaginationCircleButton
         onClick={() => onPageChange(Math.max(1, currentPage - 1))}
         disabled={currentPage === 1}
+        aria-label="이전 페이지"
       >
         ←
       </PaginationCircleButton>
       {/* ... */}
       <PaginationCircleButton
         onClick={() => onPageChange(Math.min(totalPages, currentPage + 1))}
         disabled={currentPage === totalPages}
+        aria-label="다음 페이지"
       >
         →
       </PaginationCircleButton>

Also applies to: 33-35

src/features/study/one-to-one/history/ui/study-history-header.tsx (1)

58-85: ViewModeToggle 컴포넌트 재사용 권장

src/components/ui/filters/view-mode-toggle.tsx에 동일한 기능의 ViewModeToggle 컴포넌트가 존재합니다. 코드 중복을 줄이고 일관성을 위해 해당 컴포넌트를 재사용하는 것을 권장합니다.

또한, 접근성 향상을 위해 토글 버튼에 aria-pressed 속성을 추가하는 것이 좋습니다.

♻️ ViewModeToggle 재사용 제안

+import ViewModeToggle from '@/components/ui/filters/view-mode-toggle';
+import { List, Calendar as CalendarIcon } from 'lucide-react';

// rightSlot에서 사용:
+const viewModeOptions = [
+  { value: 'LIST' as const, icon: <List className="h-4 w-4" />, title: '리스트' },
+  { value: 'CALENDAR' as const, icon: <CalendarIcon className="h-4 w-4" />, title: '달력' },
+];

// SectionHeader의 rightSlot prop:
-rightSlot={
-  <div className="bg-background-default rounded-100 border-border-subtle flex shrink-0 border p-50">
-    <button
-      onClick={() => onViewModeChange('LIST')}
-      ...
-    </button>
-    ...
-  </div>
-}
+rightSlot={
+  <ViewModeToggle
+    value={viewMode}
+    options={viewModeOptions}
+    onChange={onViewModeChange}
+  />
+}

src/components/voting/voting-option-fields.tsx (1)

57-65: 접근성: 삭제 버튼에 접근 가능한 레이블 추가 권장

스크린 리더 사용자를 위해 삭제 버튼에 aria-label 속성을 추가하는 것이 좋습니다.

♿ 접근성 개선 제안

 <button
   type="button"
   onClick={() => remove(index)}
+  aria-label={`선택지 ${index + 1} 삭제`}
   className="rounded-100 text-text-subtle hover:bg-fill-critical-subtle-default hover:text-text-critical p-150 transition-colors"
 >
   <Trash2 className="h-4 w-4" />
 </button>

src/components/ui/filters/view-mode-toggle.tsx (1)

34-46: 접근성: aria-pressed 속성 추가 권장

토글 버튼의 활성화 상태를 스크린 리더에 전달하기 위해 aria-pressed 속성을 추가하는 것이 좋습니다.

♿ 접근성 개선 제안

 <button
   key={option.value}
   onClick={() => onChange(option.value)}
+  aria-pressed={isActive}
   className={cn(
     'rounded-75 p-100 transition-colors',
     isActive
       ? 'bg-fill-neutral-default-default text-text-strong shadow-sm'
       : 'text-text-subtlest hover:text-text-subtle',
   )}
   title={option.title}
 >

src/components/ui/filters/sort-dropdown.tsx (1)

28-52: 접근성: hover 기반 드롭다운의 키보드/모바일 접근성 고려

현재 group-hover:block 방식은 마우스 hover에만 의존하여 다음 문제가 있습니다:

• 키보드 사용자가 드롭다운에 접근할 수 없음
• 터치 디바이스에서 hover 상태가 불안정함

향후 개선 시 focus-within을 추가하거나, Radix UI의 DropdownMenu 같은 접근성이 보장된 컴포넌트 사용을 권장합니다.

♻️ 간단한 개선 제안

-<div className="absolute top-full right-0 z-20 hidden w-[120px] pt-50 group-hover:block">
+<div className="absolute top-full right-0 z-20 hidden w-[120px] pt-50 group-hover:block group-focus-within:block">

src/hooks/use-scroll-to-home-content.ts (1)

61-75: ESLint react-hooks/exhaustive-deps 경고 처리 필요

deps 파라미터를 useEffect 의존성 배열로 직접 전달하면 ESLint의 react-hooks/exhaustive-deps 규칙 경고가 발생합니다. 이는 의도된 동작이므로 eslint-disable 주석을 추가하는 것이 좋습니다.

🔧 ESLint 경고 처리 제안

   useEffect(() => {
     if (options?.enabled === false) return;
     if (isFirst.current) {
       isFirst.current = false;

       return;
     }
     scrollToHomeContent();
     if (options?.stabilize) {
       stabilizeScrollAfterLayout(
         scrollToHomeContent,
         options?.stabilizeDurationMs ?? 800,
       );
     }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, deps);

src/api/client/axios.server.ts (1)

17-18: 인터셉터 등록 순서 확인 필요

attachApiLogger가 다른 인터셉터(onRequestServer) 등록 전에 호출되었습니다. 이 순서에서:

• 요청: 로거 → 토큰 추가 순으로 실행
• 응답: 에러 핸들러 → 로거 순으로 실행

토큰이 추가된 후의 요청을 로깅하려면 attachApiLogger를 다른 인터셉터 등록 후로 이동하는 것이 좋습니다.

♻️ 제안된 수정

 attachApiLogger(axiosServerInstance, 'server-json');
-
 const onRequestServer = async (config: InternalAxiosRequestConfig) => {

또는 로거를 마지막에 등록:

 axiosServerInstance.interceptors.request.use(onRequestServer);
 
 axiosServerInstance.interceptors.response.use(
   (config) => config,
   async (error) => {
     return Promise.reject(error);
   },
 );
+
+attachApiLogger(axiosServerInstance, 'server-json');

src/features/study/one-to-one/archive/model/use-update-archive-mutation.ts (1)

34-36: 타입 안전성 관련 참고 사항

{ ...item, ...request } 패턴은 UpdateArchiveRequest의 필드명이 ArchiveItem의 필드명과 일치한다고 가정합니다. 현재는 올바르게 작동하지만, 추후 API 스키마 변경 시 주의가 필요합니다.

src/features/study/one-to-one/hall-of-fame/ui/hall-of-fame-header.tsx (1)

11-12: Tailwind 클래스 정렬 적용 권장

Line 12의 className 순서가 Tailwind 정렬 규칙과 다릅니다. prettier-plugin-tailwindcss로 정렬을 한 번 적용해주세요.

✅ 정렬 예시

-        <Trophy className="text-text-warning h-8 w-8" fill="currentColor" />
+        <Trophy className="h-8 w-8 text-text-warning" fill="currentColor" />

src/features/study/one-to-one/archive/ui/archive-filters.tsx (1)

183-183: Tailwind 클래스 정렬 일괄 적용 필요

Line 183 등 다수의 className에서 정렬 규칙이 섞여 있습니다. prettier-plugin-tailwindcss로 파일 전체 정렬을 권장합니다.

src/components/voting/voting-tag-field.tsx (2)

32-36: 최대 태그 수 표기를 상수와 동기화해주세요.

라벨에 (최대 3개)가 하드코딩되어 있어 상수 변경 시 UI가 쉽게 불일치합니다. BALANCE_GAME_TAG_MAX_COUNT를 그대로 사용하는 편이 안전합니다.

🔧 제안 변경

-        <span className="font-designer-12r text-text-subtle ml-100">
-          (최대 3개)
-        </span>
+        <span className="font-designer-12r text-text-subtle ml-100">
+          (최대 {BALANCE_GAME_TAG_MAX_COUNT}개)
+        </span>

---

31-35: prettier-plugin-tailwindcss를 사용하여 Tailwind 클래스 자동 정렬을 적용해주세요.

ml-100 같은 spacing 클래스가 typography 클래스 뒤에 위치하고 있습니다. 프로젝트 코딩 가이드라인에 따라 prettier-plugin-tailwindcss의 자동 정렬 규칙으로 클래스 순서를 통일해주세요. 이렇게 하면 Tailwind의 CSS 생성 순서(base → components → utilities)에 맞게 자동으로 정렬됩니다.

src/features/study/one-to-one/schedule/ui/study-tutorial-controller.tsx (1)

6-10: src 내부 import는 @/ alias로 통일해주세요.

상대경로 대신 @/ alias를 사용하면 경로 안정성과 일관성이 좋아집니다.

🔧 제안 변경

-import StudyCard from './study-card';
-import {
-  STUDY_TUTORIAL_STEPS,
-  getStudyTutorialScenario,
-} from '../model/study-tutorial-steps';
+import StudyCard from '@/features/study/one-to-one/schedule/ui/study-card';
+import {
+  STUDY_TUTORIAL_STEPS,
+  getStudyTutorialScenario,
+} from '@/features/study/one-to-one/schedule/model/study-tutorial-steps';

As per coding guidelines, **/*.{ts,tsx,js,jsx}: Use path alias @/* to reference src/* directory as configured in tsconfig.json for import statements.

src/components/tutorial/index.ts (1)

1-2: 튜토리얼 모듈도 @/ alias 사용을 권장합니다.

상대경로 대신 alias로 통일하면 경로 변경에 강해집니다.

🔧 제안 변경

-export { default as TutorialOverlay } from './tutorial-overlay';
-export type { TutorialStep } from './tutorial-overlay';
+export { default as TutorialOverlay } from '@/components/tutorial/tutorial-overlay';
+export type { TutorialStep } from '@/components/tutorial/tutorial-overlay';

As per coding guidelines, **/*.{ts,tsx,js,jsx}: Use path alias @/* to reference src/* directory as configured in tsconfig.json for import statements.

src/components/ui/action-pill-button.tsx (2)

13-44: CVA를 사용하여 variant/size 클래스 관리를 일관되게 정리하세요.

프로젝트의 다른 UI 컴포넌트들(radio, toggle, pagination, input, chip, badge, button, tab-menu)은 모두 CVA를 사용 중이므로, 이 컴포넌트도 동일한 패턴을 따르면 타입 안정성과 확장성이 향상됩니다.

🔧 CVA 적용 예시

+import { cva } from 'class-variance-authority';
 import { cn } from '@/components/ui/(shadcn)/lib/utils';
 
-type ActionPillVariant = 'primary' | 'neutral' | 'ghost';
-type ActionPillSize = 'xs' | 'sm' | 'md';
+type ActionPillVariant = 'primary' | 'neutral' | 'ghost';
+type ActionPillSize = 'xs' | 'sm' | 'md';
 
-const VARIANT_CLASSES: Record<ActionPillVariant, string> = {
-  primary:
-    'bg-fill-brand-default-default text-text-inverse hover:bg-fill-brand-default-hover',
-  neutral:
-    'bg-background-alternative text-text-subtle hover:bg-fill-neutral-subtle-hover',
-  ghost:
-    'bg-background-default text-text-subtle hover:bg-fill-neutral-subtle-hover',
-};
-
-const SIZE_CLASSES: Record<ActionPillSize, string> = {
-  xs: 'px-100 py-50 font-designer-11m',
-  sm: 'px-150 py-50 font-designer-12m',
-  md: 'px-200 py-100 font-designer-12m',
-};
+const actionPill = cva(
+  'rounded-100 flex items-center gap-50 transition-colors',
+  {
+    variants: {
+      variant: {
+        primary:
+          'bg-fill-brand-default-default text-text-inverse hover:bg-fill-brand-default-hover',
+        neutral:
+          'bg-background-alternative text-text-subtle hover:bg-fill-neutral-subtle-hover',
+        ghost:
+          'bg-background-default text-text-subtle hover:bg-fill-neutral-subtle-hover',
+      },
+      size: {
+        xs: 'px-100 py-50 font-designer-11m',
+        sm: 'px-150 py-50 font-designer-12m',
+        md: 'px-200 py-100 font-designer-12m',
+      },
+    },
+    defaultVariants: { variant: 'ghost', size: 'sm' },
+  },
+);
 
   return (
     <button
       type="button"
       className={cn(
-        'rounded-100 flex items-center gap-50 transition-colors',
-        VARIANT_CLASSES[variant],
-        SIZE_CLASSES[size],
+        actionPill({ variant, size }),
         className,
       )}

---

1-2: CVA를 사용하여 동적 클래스 관리를 리팩토링하세요.

현재 VARIANT_CLASSES와 SIZE_CLASSES 객체로 스타일을 관리하고 있습니다. 코딩 가이드라인에 따라 class-variance-authority(CVA)를 사용하여 variant와 size 조합을 더 명확하게 관리하는 것을 추천합니다.

참고: use client 지시어는 필요하지 않습니다. 이 컴포넌트는 이벤트 핸들러 props를 상위 클라이언트 컴포넌트(archive-tab-client.tsx)로부터 받으므로 서버 컴포넌트로 유지될 수 있습니다.

src/features/study/one-to-one/hall-of-fame/ui/hall-of-fame-mvp-section.tsx (1)

16-26: Tailwind 클래스 정렬을 플러그인 규칙으로 맞춰주세요.

Line 17, Line 25 등에서 className 순서가 Tailwind 정렬 규칙과 다릅니다. prettier-plugin-tailwindcss로 자동 정렬해주세요.

♻️ 제안되는 정렬 예시

-      <h3 className="font-display-headings6 text-text-strong flex items-center gap-100">
-        <Users className="text-text-information h-5 w-5" />
+      <h3 className="flex items-center gap-100 font-display-headings6 text-text-strong">
+        <Users className="h-5 w-5 text-text-information" />
       </h3>
...
-        <div className="bg-background-default border-border-subtle rounded-200 flex h-[400px] items-center justify-center border">
+        <div className="flex h-[400px] items-center justify-center rounded-200 border border-border-subtle bg-background-default">

As per coding guidelines: **/*.{tsx,ts,jsx,js}: Organize Tailwind CSS classes using prettier-plugin-tailwindcss for automatic class ordering and sort them alphabetically within groups.

src/features/study/one-to-one/archive/api/get-archive-search-suggestions.ts (1)

7-13: 응답 타입 가드에서 배열 여부까지 검증해주세요.

Line 7-13은 키 존재만 확인해 titles/authors가 배열이 아니어도 통과합니다. 배열 체크로 안정성을 높이는 편이 안전합니다.

♻️ 제안 수정안

-const isArchiveSearchSuggestionResponse = (
-  value: unknown,
-): value is ArchiveSearchSuggestionResponse =>
-  !!value &&
-  typeof value === 'object' &&
-  'titles' in value &&
-  'authors' in value;
+const isArchiveSearchSuggestionResponse = (
+  value: unknown,
+): value is ArchiveSearchSuggestionResponse =>
+  !!value &&
+  typeof value === 'object' &&
+  Array.isArray((value as ArchiveSearchSuggestionResponse).titles) &&
+  Array.isArray((value as ArchiveSearchSuggestionResponse).authors);

src/features/study/one-to-one/hall-of-fame/ui/mvp-team-card.tsx (1)

18-40: Tailwind 클래스 순서를 플러그인 규칙으로 정렬해주세요.

Line 19-21, Line 39 등 여러 className이 순서 규칙과 다릅니다. prettier-plugin-tailwindcss로 정렬해주세요.

♻️ 정렬 예시

-      className={cn(
-        'rounded-200 shadow-2 relative overflow-hidden border border-[`#FFEBA4`] bg-gradient-to-br from-[`#FFF8E7`] to-[`#FFF`] p-500',
-        className,
-      )}
+      className={cn(
+        'relative overflow-hidden rounded-200 border border-[`#FFEBA4`] bg-gradient-to-br from-[`#FFF8E7`] to-[`#FFF`] p-500 shadow-2',
+        className,
+      )}
...
-              className="border-border-subtle text-text-strong bg-background-default shadow-1 font-designer-24b flex h-600 w-600 items-center justify-center rounded-full border leading-none"
+              className="flex h-600 w-600 items-center justify-center rounded-full border border-border-subtle bg-background-default font-designer-24b leading-none text-text-strong shadow-1"

As per coding guidelines: `**/*.{tsx,ts,jsx,js}`: Organize Tailwind CSS classes using prettier-plugin-tailwindcss for automatic class ordering and sort them alphabetically within groups.

src/features/study/one-to-one/archive/ui/archive-pagination.tsx (1)

28-30: Tailwind 클래스 정렬을 플러그인 규칙으로 맞춰주세요.

Line 28 className 순서가 정렬 규칙과 다릅니다. prettier-plugin-tailwindcss로 통일해주세요.

♻️ 정렬 예시

-      <span className="font-designer-15m text-text-subtle bg-background-default border-border-subtle flex h-[40px] items-center justify-center rounded-[9999px] border px-300">
+      <span className="flex h-[40px] items-center justify-center rounded-[9999px] border border-border-subtle bg-background-default px-300 font-designer-15m text-text-subtle">

As per coding guidelines: `**/*.{tsx,ts,jsx,js}`: Organize Tailwind CSS classes using prettier-plugin-tailwindcss for automatic class ordering and sort them alphabetically within groups.

src/components/ui/filters/filter-pill-button.tsx (1)

24-31: 상태별 클래스는 CVA로 분리하는 게 유지보수에 유리합니다
isActive/disabled 조합이 늘어나면 조건식이 복잡해지므로, cva로 variant를 정의해 관리하는 편이 안전합니다.

♻️ 제안 수정안

-import { cn } from '@/components/ui/(shadcn)/lib/utils';
+import { cn } from '@/components/ui/(shadcn)/lib/utils';
+import { cva } from 'class-variance-authority';
+
+const filterPillButtonVariants = cva(
+  'rounded-100 px-300 py-150 font-designer-13b transition-all',
+  {
+    variants: {
+      isActive: {
+        true: 'bg-fill-brand-default-default text-text-inverse shadow-1',
+        false:
+          'border border-border-subtle bg-background-default text-text-subtle hover:border-border-brand hover:text-text-brand',
+      },
+      disabled: {
+        true: 'cursor-not-allowed opacity-50',
+      },
+    },
+    defaultVariants: {
+      isActive: false,
+      disabled: false,
+    },
+  },
+);
@@
-      className={cn(
-        'rounded-100 font-designer-13b px-300 py-150 transition-all',
-        isActive
-          ? 'bg-fill-brand-default-default text-text-inverse shadow-1'
-          : 'border-border-subtle bg-background-default text-text-subtle hover:border-border-brand hover:text-text-brand border',
-        disabled && 'cursor-not-allowed opacity-50',
-        className,
-      )}
+      className={cn(filterPillButtonVariants({ isActive, disabled }), className)}

As per coding guidelines, Use class composition utilities clsx, tailwind-merge, and class-variance-authority (CVA) for dynamic Tailwind class management.

src/features/study/one-to-one/hall-of-fame/ui/rank-badge.tsx (1)

11-28: SVG는 SVGR 컴포넌트로 import해 사용하세요
문자열 경로 대신 SVGR로 불러오면 스타일/테마 적용과 번들 최적화가 쉬워집니다. 아이콘 경로는 프로젝트 위치에 맞춰 조정해주세요.

♻️ 제안 수정안

-import Image from 'next/image';
+import GoldRankIcon from '@/assets/icons/gold-rank.svg';
+import SilverRankIcon from '@/assets/icons/silver-rank.svg';
+import BronzeRankIcon from '@/assets/icons/bronze-rank.svg';
@@
-  const iconPath =
-    rank === 1
-      ? '/icons/gold-rank.svg'
-      : rank === 2
-        ? '/icons/silver-rank.svg'
-        : '/icons/bronze-rank.svg';
+  const Icon =
+    rank === 1 ? GoldRankIcon : rank === 2 ? SilverRankIcon : BronzeRankIcon;
@@
-  return (
-    <div className="relative h-[48px] w-[36px] md:h-[60px] md:w-[45px]">
-      <Image src={iconPath} alt={`${rank}위`} fill className="object-contain" />
-    </div>
-  );
+  return (
+    <div className="relative h-[48px] w-[36px] md:h-[60px] md:w-[45px]">
+      <Icon className="h-full w-full" aria-label={`${rank}위`} />
+    </div>
+  );

As per coding guidelines, Import and use SVG files as React components via @svgr/webpack configured in next.config.ts.

src/features/study/one-to-one/hall-of-fame/ui/hall-of-fame-ranker-section.tsx (1)

5-8: src 경로는 @/ 별칭으로 통일해주세요
가이드라인상 src/* import는 @/ 경로를 사용해야 합니다. 동일 폴더라도 별칭으로 맞추면 일관성이 좋아집니다.

♻️ 제안 수정안

-import type { RankingType, RankerWithLabel } from './hall-of-fame-constants';
-import { TAB_CONFIG } from './hall-of-fame-constants';
-import RankerListItem from './ranker-list-item';
-import RankingTabButton from './ranking-tab-button';
+import type { RankingType, RankerWithLabel } from '@/features/study/one-to-one/hall-of-fame/ui/hall-of-fame-constants';
+import { TAB_CONFIG } from '@/features/study/one-to-one/hall-of-fame/ui/hall-of-fame-constants';
+import RankerListItem from '@/features/study/one-to-one/hall-of-fame/ui/ranker-list-item';
+import RankingTabButton from '@/features/study/one-to-one/hall-of-fame/ui/ranking-tab-button';

As per coding guidelines, Use path alias @/* to reference src/* directory as configured in tsconfig.json for import statements.

src/components/card/voting-card.tsx (2)

23-41: 비활성 상태 클래스가 현재는 중복

기본 클래스에 이미 bg-background-default가 있어 !isActive 조건이 효과가 없습니다. 의도된 스타일이 없다면 조건을 제거하는 편이 낫습니다.

✏️ 수정 제안

-        !isActive && 'bg-background-default',

---

144-149: 불필요한 분기/주석 정리 권장

onClick 유무와 무관하게 동일 반환이라 분기와 주석이 의미가 없습니다. 단순 반환으로 정리하세요.

✏️ 수정 제안

-  // onClick이 있으면 Link 없이 렌더링, 없으면 Link로 감싸기
-  if (onClick) {
-    return cardContent;
-  }
-
-  return cardContent;
+  // 현재는 Link 래핑 없이 동일한 cardContent를 반환
+  return cardContent;

src/features/study/one-to-one/balance-game/ui/balance-game-filters-bar.tsx (1)

216-296: 검색 제안 드롭다운 조건부 렌더링 로직 개선 고려

현재 드롭다운 표시 조건이 두 곳(Lines 216-296, 297-308)에 분리되어 있고, flatSuggestions.length > 0 || isFetching 조건과 !isFetching && flatSuggestions.length === 0 조건이 중복된 검사를 수행합니다. 가독성과 유지보수를 위해 하나의 조건부 블록으로 통합하는 것을 권장합니다.

♻️ 통합 제안

-            {isOpen &&
-              (flatSuggestions.length > 0 || isFetching) &&
-              searchTerm.trim().length >= minQueryLength && (
-                <div className="absolute top-full left-0 z-30 mt-100 w-full">
-                  ...
-                </div>
-              )}
-            {isOpen &&
-              !isFetching &&
-              flatSuggestions.length === 0 &&
-              searchTerm.trim().length >= minQueryLength && (
-                <div className="absolute top-full left-0 z-30 mt-100 w-full">
-                  ...
-                </div>
-              )}
+            {isOpen && searchTerm.trim().length >= minQueryLength && (
+              <div className="absolute top-full left-0 z-30 mt-100 w-full">
+                <div className="bg-background-default border-border-subtle rounded-150 shadow-2 overflow-hidden border py-100">
+                  {isFetching ? (
+                    <div className="font-designer-13r text-text-subtlest px-200 py-150">
+                      검색 중...
+                    </div>
+                  ) : flatSuggestions.length === 0 ? (
+                    <div className="font-designer-13r text-text-subtlest px-200 py-150">
+                      검색 결과가 없습니다
+                    </div>
+                  ) : (
+                    <>
+                      {/* title and author sections */}
+                    </>
+                  )}
+                </div>
+              </div>
+            )}

src/features/study/one-to-one/hall-of-fame/ui/hall-of-fame-constants.ts (1)

39-57: addScoreLabel에서 TAB_CONFIG.unit 재사용 권장

addScoreLabel 함수에서 단위 문자열('회', '건', '℃')이 TAB_CONFIG의 unit 필드와 중복되어 있습니다. DRY 원칙에 따라 TAB_CONFIG를 활용하면 유지보수성이 향상됩니다.

♻️ 리팩토링 제안

 export const addScoreLabel = (
   ranker: Ranker,
   type: RankingType,
 ): RankerWithLabel => {
-  let scoreLabel = '';
-
-  if (type === 'ATTENDANCE') {
-    scoreLabel = `${ranker.score}회`;
-  } else if (type === 'STUDY_LOG') {
-    scoreLabel = `${ranker.score}건`;
-  } else {
-    scoreLabel = `${ranker.score}℃`;
-  }
+  const { unit } = TAB_CONFIG[type];
+  const scoreLabel = `${ranker.score}${unit}`;
 
   return {
     ...ranker,
     scoreLabel,
   };
 };

src/features/study/one-to-one/balance-game/ui/tag-autocomplete.tsx (1)

58-71: 클릭 외부 처리 로직 중복

이 컴포넌트의 click-outside 핸들링 로직(Lines 58-71)이 balance-game-filters-bar.tsx(Lines 79-92)와 동일합니다. 재사용 가능한 커스텀 훅(useClickOutside)으로 추출하면 코드 중복을 줄이고 유지보수성을 높일 수 있습니다.

♻️ 커스텀 훅 추출 제안

// src/hooks/use-click-outside.ts
import { useEffect, RefObject } from 'react';

export const useClickOutside = (
  ref: RefObject<HTMLElement>,
  isActive: boolean,
  onClickOutside: () => void
) => {
  useEffect(() => {
    if (!isActive) return;
    const handleClickOutside = (event: MouseEvent) => {
      if (!ref.current) return;
      if (!ref.current.contains(event.target as Node)) {
        onClickOutside();
      }
    };
    document.addEventListener('mousedown', handleClickOutside);
    return () => document.removeEventListener('mousedown', handleClickOutside);
  }, [isActive, onClickOutside, ref]);
};

Also applies to: 79-92

src/components/voting/voting-create-modal.tsx (1)

85-93: minLength 파라미터가 중복 사용되고 있습니다.

enabled 조건(line 90)과 minLength 옵션(line 91) 모두에서 BALANCE_GAME_TAG_MIN_QUERY_LEN을 사용하고 있습니다. useBalanceGameTagSuggestionsQuery 훅 내부에서 이미 minLength를 기반으로 enabled를 계산하므로, 외부에서 enabled를 직접 지정할 필요가 없을 수 있습니다.

♻️ 간소화 제안

  const { data: tagSuggestions = [], isFetching: isTagLoading } =
    useBalanceGameTagSuggestionsQuery(trimmedTagQuery, {
      limit: 10,
-     enabled: trimmedTagQuery.length >= BALANCE_GAME_TAG_MIN_QUERY_LEN,
      minLength: BALANCE_GAME_TAG_MIN_QUERY_LEN,
      sort: 'popular',
    });

src/features/study/one-to-one/balance-game/ui/community-tab-client.tsx (1)

273-280: key에서 index 사용이 불필요해 보입니다.

voting.id가 고유하다면 ${voting.id}-${index} 대신 voting.id만 사용해도 충분합니다. index를 추가하면 동일한 ID가 있는 경우 버그를 숨길 수 있고, React의 재조정 최적화에도 영향을 줄 수 있습니다.

♻️ 간소화 제안

-              {visibleVotings.map((voting, index) => (
+              {visibleVotings.map((voting) => (
                 <VotingCard
-                  key={`${voting.id}-${index}`}
+                  key={voting.id}
                   voting={voting}

src/components/tutorial/tutorial-overlay.tsx (2)

240-252: 타겟 요소를 찾지 못했을 때의 처리 개선 필요

missingCountRef가 20에 도달한 후 0으로 리셋되고 아무 동작도 하지 않습니다. 타겟 요소를 찾을 수 없는 경우, 다음 단계로 이동하거나 오버레이를 닫거나, 적어도 경고를 출력하는 것이 좋습니다.

♻️ 개선 제안

      if (missingCountRef.current <= 20) {
        const id = window.setTimeout(() => {
          setRecheckKey((prev) => prev + 1);
        }, 50);

        return () => window.clearTimeout(id);
      }
      missingCountRef.current = 0;
+     // 타겟을 찾지 못한 경우 다음 단계로 건너뛰거나 경고 출력
+     console.warn(`Tutorial target not found for step: ${step.id}`);
+     if (resolvedActiveIndex < steps.length - 1) {
+       setStepIndex(resolvedActiveIndex + 1);
+     } else {
+       requestClose();
+     }

      return;

---

442-472: 버튼 스타일을 공통 컴포넌트로 통일하는 것을 고려해 보세요

현재 인라인 스타일로 버튼이 정의되어 있습니다. 코드베이스에 ActionPillButton 같은 공통 버튼 컴포넌트가 있으니, 일관성을 위해 해당 컴포넌트를 사용하거나 Tailwind 클래스를 활용하는 것을 권장합니다.

src/features/study/one-to-one/archive/ui/archive-grid.tsx (1)

23-268: LibraryRow와 LibraryCard의 편집 로직 중복 고려

archive-list.tsx의 LibraryRow와 이 파일의 LibraryCard가 거의 동일한 인라인 편집 로직(상태 관리, handleSave, handleCancel, useEffect)을 가지고 있습니다. 향후 유지보수를 위해 공통 로직을 커스텀 훅으로 추출하는 것을 고려해 보세요.

♻️ 커스텀 훅 추출 예시

// useArchiveEditing.ts
export function useArchiveEditing(
  item: ArchiveItem,
  onUpdate: (id: number, request: UpdateArchiveRequest) => void,
) {
  const [isEditing, setIsEditing] = React.useState(false);
  const [title, setTitle] = React.useState(item.title);
  const [description, setDescription] = React.useState(item.description ?? '');
  const [nextPrivate, setNextPrivate] = React.useState(!!item.isPrivate);

  React.useEffect(() => {
    if (!isEditing) {
      setTitle(item.title);
      setDescription(item.description ?? '');
      setNextPrivate(!!item.isPrivate);
    }
  }, [isEditing, item.title, item.description, item.isPrivate]);

  const handleSave = (e: React.MouseEvent) => {
    e.stopPropagation();
    const request: UpdateArchiveRequest = {};
    // ... save logic
  };

  const handleCancel = (e: React.MouseEvent) => {
    e.stopPropagation();
    setIsEditing(false);
    setTitle(item.title);
    setDescription(item.description ?? '');
    setNextPrivate(!!item.isPrivate);
  };

  return {
    isEditing,
    setIsEditing,
    title,
    setTitle,
    description,
    setDescription,
    nextPrivate,
    setNextPrivate,
    handleSave,
    handleCancel,
  };
}

src/components/ui/modal-shell.tsx (1)

30-30: Tailwind 클래스 순서를 가이드라인에 맞춰 정렬해 주세요.
Modal.Header의 className 순서가 정렬 규칙과 다릅니다. prettier-plugin-tailwindcss 기준으로 정렬하면 규칙과 자동 정렬이 일치합니다.

✅ 정렬 예시

-          <Modal.Header className="border-border-default flex items-center justify-between border-b">
+          <Modal.Header className="flex items-center justify-between border-b border-border-default">

As per coding guidelines: `**/*.{tsx,ts,jsx,js}`: Organize Tailwind CSS classes using prettier-plugin-tailwindcss for automatic class ordering and sort them alphabetically within groups.

src/features/study/interview/ui/study-ready-modal.tsx (1)

78-79: Footer 컨테이너의 Tailwind 클래스 정렬을 맞춰 주세요.
prettier-plugin-tailwindcss 기준으로 정렬해 두면 팀 규칙과 자동 정렬이 일치합니다.

✅ 정렬 예시

-        <div className="flex justify-end gap-100">
+        <div className="flex gap-100 justify-end">

As per coding guidelines: `**/*.{tsx,ts,jsx,js}`: Organize Tailwind CSS classes using prettier-plugin-tailwindcss for automatic class ordering and sort them alphabetically within groups.

src/features/study/interview/ui/study-done-modal.tsx (1)

91-92: Footer 컨테이너의 Tailwind 클래스 정렬을 맞춰 주세요.
prettier-plugin-tailwindcss 기준 정렬로 통일하는 편이 좋습니다.

✅ 정렬 예시

-        <div className="flex justify-end gap-100">
+        <div className="flex gap-100 justify-end">

As per coding guidelines: `**/*.{tsx,ts,jsx,js}`: Organize Tailwind CSS classes using prettier-plugin-tailwindcss for automatic class ordering and sort them alphabetically within groups.